View RX77016_9013041.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

application note target devices m m m m pd77016 m m m m pd77017 m m m m pd77018 m m m m pd77018a m m m m pd77019 m m m m pd77110 m m m m pd77111 m m m m pd77112 m m m m pd77113 m m m m pd77114 RX77016 real-time operating system host api document no. u14371ej1v0anj1 (1st edition) date published october 2000 n cp(k) printed in japan 1999 ?
$ssolfdwlrqy1rwhy8?(-9$1 2 [memo]
$ssolfdwlrqy1rwhy8?(-9$1 3 windows is either a registered trademark or a trademark of microsoft corporation in the united states and/or other countries. m8e 00. 4 the information in this document is current as of october, 1999. the information is subject to change without notice. for actual design-in, refer to the latest publications of nec's data sheets or data books, etc., for the most up-to-date specifications of nec semiconductor products. not all products and/or types are available in every country. please check with an nec sales representative for availability and additional information. no part of this document may be copied or reproduced in any form or by any means without prior written consent of nec. nec assumes no responsibility for any errors that may appear in this document. nec does not assume any liability for infringement of patents, copyrights or other intellectual property rights of third parties by or arising from the use of nec semiconductor products listed in this document or any other liability arising from the use of such products. no license, express, implied or otherwise, is granted under any patents, copyrights or other intellectual property rights of nec or others. descriptions of circuits, software and other related information in this document are provided for illustrative purposes in semiconductor product operation and application examples. the incorporation of these circuits, software and information in the design of customer's equipment shall be done under the full responsibility of customer. nec assumes no responsibility for any losses incurred by customers or third parties arising from the use of these circuits, software and information. while nec endeavours to enhance the quality, reliability and safety of nec semiconductor products, customers agree and acknowledge that the possibility of defects thereof cannot be eliminated entirely. to minimize risks of damage to property or injury (including death) to persons arising from defects in nec semiconductor products, customers must incorporate sufficient safety measures in their design, such as redundancy, fire-containment, and anti-failure features. nec semiconductor products are classified into the following three quality grades: "standard", "special" and "specific". the "specific" quality grade applies only to semiconductor products developed based on a customer-designated "quality assurance program" for a specific application. the recommended applications of a semiconductor product depend on its quality grade, as indicated below. customers must check the quality grade of each semiconductor product before using it in a particular application. "standard": computers, office equipment, communications equipment, test and measurement equipment, audio and visual equipment, home electronic appliances, machine tools, personal electronic equipment and industrial robots "special": transportation equipment (automobiles, trains, ships, etc.), traffic control systems, anti-disaster systems, anti-crime systems, safety equipment and medical equipment (not specifically designed for life support) "specific": aircraft, aerospace equipment, submersible repeaters, nuclear reactor control systems, life support systems and medical equipment for life support, etc. the quality grade of nec semiconductor products is "standard" unless otherwise expressly specified in nec's data sheets or data books, etc. if customers wish to use nec semiconductor products in applications not intended by nec, they must contact an nec sales representative in advance to determine nec's willingness to support a given application. (note) (1) "nec" as used in this statement means nec corporation and also includes its majority-owned subsidiaries. (2) "nec semiconductor products" means any semiconductor product developed or manufactured by or for nec (as defined above).
$ssolfdwlrqy1rwhy8?(-9$1 4 regional information some information contained in this document may vary from country to country. before using any nec product in your application, piease contact the nec office in your country to obtain a list of authorized representatives and distributors. they will verify: device availability ordering information product release schedule availability of related technical literature development environment specifications (for example, specifications for third-party tools and components, host computers, power plugs, ac supply voltages, and so forth) network requirements in addition, trademarks, registered trademarks, export restrictions, and other legal issues may also vary from country to country. nec electronics inc. (u.s.) santa clara, california tel: 408-588-6000 800-366-9782 fax: 408-588-6130 800-729-9288 nec electronics (germany) gmbh duesseldorf, germany tel: 0211-65 03 02 fax: 0211-65 03 490 nec electronics (uk) ltd. milton keynes, uk tel: 01908-691-133 fax: 01908-670-290 nec electronics italiana s.r.l. milano, italy tel: 02-66 75 41 fax: 02-66 75 42 99 nec electronics (germany) gmbh benelux office eindhoven, the netherlands tel: 040-2445845 fax: 040-2444580 nec electronics (france) s.a. velizy-villacoublay, france tel: 01-30-67 58 00 fax: 01-30-67 58 99 nec electronics (france) s.a. madrid office madrid, spain tel: 91-504-2787 fax: 91-504-2860 nec electronics (germany) gmbh scandinavia office taeby, sweden tel: 08-63 80 820 fax: 08-63 80 388 nec electronics hong kong ltd. hong kong tel: 2886-9318 fax: 2886-9022/9044 nec electronics hong kong ltd. seoul branch seoul, korea tel: 02-528-0303 fax: 02-528-4411 nec electronics singapore pte. ltd. united square, singapore tel: 65-253-8311 fax: 65-250-3583 nec electronics taiwan ltd. taipei, taiwan tel: 02-2719-2377 fax: 02-2719-5951 nec do brasil s.a. electron devices division guarulhos-sp brasil tel: 55-11-6462-6810 fax: 55-11-6462-6829 j00.7
application note u14371ej1v0an00 5 introduction target readers this application note is intended for users who wish to understand the functions of the m pd77016 family and to design application programs using these microcontrollers. the m m m m pd77016 family comprises the m m m m pd77016, 77017, 77018, 77018a, 77019, 77110, 77111, 77112, 77113, and 77114. unless otherwise specified, the m m m m pd77016 is treated as the representative product in this document in describing functions that are shared by all the above-listed products. purpose this application note is intended to give users an understanding of host api, which is an api (application program interface) that supports data communication between a m pd77016 family product that mounts the RX77016 and the host processor. the configuration of the loaded program is indicated for illustration purposes only, and is not to be used for mass-production design. organization this application note describes the configuration and mechanism of host api, as well as the api functions and bios functions. how to read this manual it is assumed that the reader of this manual has general knowledge in the fields of logic circuits, microcontrollers, c language, and windows tm . to learn about the functions of the RX77016: ? refer to the RX77016 user's manual functions . to learn how to use the RX77016 configuration tool: ? refer to the RX77016 user's manual configuration tool . to learn about the hardware functions of the m pd77016 family: ? refer to the m m m m pd7701x family user's manual architecture . to learn about the instruction functions of the m pd77016 family ? refer to the m m m m pd7701x family user's manual instructions . conventions data significance: higher digits on the left and lower digits on the right active low representation: (overscore over pin or signal name) note: footnote for item marked with note in the text caution: information requiring particular attention remark: supplementary information numerical representation: binary... or 0b decimal: hexadecimal: 0x
application note u14371ej1v0an00 6 expression format in this application note, api functions are expressed by appending "()" to indicate the fact that they are c language function, and bios functions are expressed by appending ":" to indicate that they are m pd77016 assembly language level. example api function "opendev" ? "opendev()" bios function "echoword" ? "echoword:" in host api for RX77016, the m pd77016 family is assumed as the digital signal processor (dsp) on the target system, but in this application note, the digital signal processor is simply described as the dsp. in this application note, the july 1999 version of host api for RX77016 is described as the current version. * indicates the memory contents having as their address. example if the contents of the dp0 register are 0x1000, *dp0 indicates the memory contents of address 0 1000.
application note u14371ej1v0an00 7 related documents the related documents indicated in this publication may include preliminary versions. however, preliminary versions are not marked as such. documents related to devices user's manual application note document name product name pamphlet data sheet architecture instructions basic software m pd77016 u10891e m pd77017 m pd77018 u10902e m pd77018a m pd77019 u11849e m pd77019-013 u13053e u10503e m pd77110 m pd77111 m pd77112 u12801e m pd77113 m pd77114 u12395e u14373e to be prepared u13116e u11958e documents related to development tools document name document number ie-77016-98/pc user's manual hardware eeu-1541 ie-77016-cm-lc user's manual u14139e functions u14397e RX77016 user's manual configuration tool u14371e RX77016 application note host api this manual caution the above documents are subject to change without prior notice. be sure to use the latest version document when starting design.
application note u14371ej1v0an00 8 [memo]
9 application note u14371ej1v0an00 contents chapter 1 overview .......................................................................................................... ............ 13 1.1 outline of api functions ................................................................................................. ....... 13 1.2 outline of bios functions ................................................................................................ ..... 14 chapter 2 host api configuration ......................................................................................... 15 2.1 software configuration ................................................................................................... ....... 15 2.2 hardware configuration ................................................................................................... ...... 17 chapter 3 host api functions ................................................................................................ .. 19 3.1 opening and closing communication path......................................................................... 19 3.2 data setting to os communication area ............................................................................. 20 3.3 reboot ................................................................................................................... ................... 21 3.4 data memory access ....................................................................................................... ....... 22 3.5 communication buffer ..................................................................................................... ...... 23 3.5.1 securing and releasing communication buffer area.................................................................... 24 3.5.2 communication buffer access............................................................................................ ......... 26 3.6 task management .......................................................................................................... ......... 28 chapter 4 input files....................................................................................................... ............. 29 4.1 information files ........................................................................................................ ............. 29 4.1.1 device section......................................................................................................... .................... 29 4.1.2 io resource section.................................................................................................... ........... 29 4.1.3 task section........................................................................................................... ..................... 32 4.1.4 taskxx section ......................................................................................................... .................. 32 4.1.5 subtaskxxyy section.................................................................................................... ............ 32 4.1.6 information file description example ................................................................................... ........ 33 4.2 hex file................................................................................................................. ................... 34 chapter 5 host api system................................................................................................... ...... 35 5.1 bios mode ................................................................................................................ ............... 35 5.2 bios function call....................................................................................................... ........... 36 chapter 6 api functions..................................................................................................... ......... 37 6.1 data definition.......................................................................................................... ............... 37 6.2 api application functions ................................................................................................ ..... 39 6.2.1 initial setting functions .............................................................................................. .................. 39 6.2.2 task management functions.............................................................................................. ......... 44 6.2.3 memory access functions ................................................................................................ ........... 47 6.2.4 host api management functions .......................................................................................... .... 64 chapter 7 bios functions.................................................................................................... ....... 67 7.1. action upon occurrence of hi interrupt .............................................................................. 67 7.2. bios functions .......................................................................................................... ............ 67
10 application note u14371ej1v0an00 chapter 8 preparation of host api execution file.......................................................... 77 8.1 preparation of execution file using api functions ............................................................ 77 8.1.1 hapiucfg.h............................................................................................................. ....................... 77 8.1.2 spx.c.................................................................................................................. .......................... 78 8.2 preparation of execution file using bios functions ......................................................... 79 8.2.1 os_udef.h .............................................................................................................. ...................... 79 8.2.2 target system initialization block (_mos_targetsysinit:)........................................................... 79 8.2.3 hi interrupt handler code block (_mos_ivhi:)........................................................................... .. 79 8.2.4 biosucfg.h............................................................................................................. ....................... 80
11 application note u14371ej1v0an00 list of figures figure no. title page 2-1 software configuration image .............................................................................................. .................. 15 2-2 hardware configuration image.............................................................................................. ................. 17 2-3 byte access image......................................................................................................... ........................ 18 3-1 image of communication path opening and closing (support of multiple devices).............................. 19 3-2 image of data setting to os communication area ............................................................................ .... 20 3-3 reboot image .............................................................................................................. ........................... 21 3-4 data memory access image .................................................................................................. ................ 22 3-5 communication buffer image ................................................................................................ ................. 23 3-6 image of securing communication buffer area ............................................................................... ...... 24 3-7 image of releasing usage area............................................................................................. ................ 25 3-8 image of communication buffer access ...................................................................................... .......... 26 3-9 task management image..................................................................................................... .................. 28 4-1 information file description example...................................................................................... ............... 33 4-2 image of reeboot using extension intel hex file ........................................................................... ...... 34 5-1 change in bios mode when calling opendev(), closedev()............................................................. 35 5-2 bios kernel operation flow ................................................................................................ .................. 36 6-1 read communication buffer read destination address........................................................................ 53 6-2 write communication buffer write destination address ...................................................................... .. 55
12 application note u14371ej1v0an00 list of tables figure no. title page 3-1 list of communication buffer access states................................................................................ .......... 27 6-1 data types .................................................................................................................. ........................... 37 6-2 character constants....................................................................................................... ........................ 38 7-1 shift amount and jump destination ........................................................................................ ............... 68 7-2 *_mha_pcmdptr:mem contents and jump destination........................................................................ 69 7-3 call addresses and reboot routines........................................................................................ ............. 70
application note u14371ej1v0an00 13 chapter 1 overview host api is a program interface provided for user applications for performing data communication between the m pd77016 family and the host processor note . data communications for all user applications are performed via host api. note in the current version of host api for RX77016, a personal computer (pc) is assumed as the host processor. 1.1 outline of api functions the api functions provided by the host api system are outlined below. for more details about api functions, refer to chapter 6 api functions . (1) initial setting functions the following initial setting functions are provided for target devices. opendev() ... opens communication path closedev() ... closes communication path rebootdev() ... performs host boot/self boot resetdev() ... resets system setcommunicatevalue() ... sets data to os communication area (2) task management functions the following task management functions are provided for specific tasks of target devices. showtask() ... outputs task information resumesynctask() ... changes value of frame counter a suspendsynctask() ... clears value of frame counter a to 0 (3) memory access functions the following memory access functions are provided for specific data memory or communication buffers of target devices (refer to 3.5 communication buffers .) createcbuf() ... secures communication buffer area freecbuf() ... releases communication buffer area getcbufcaps() ... displays communication buffer information initcbuf() ... clears communication buffer to 0 readfromtmem() ... reads 1 data from x or y memory writetotmem() ... writes 1 data to x or y memory readfromcbuf() ... reads 1 data from communication buffer writetocbuf() ... writes 1 data to communication buffer copytmemtohost() ... copies from memory on host to x or y memory copyhosttotmem() ... copies from x or y memory to memory on host copycbuftohost() ... copies from communication buffer to memory on host copyhosttocbuf() ... copies from memory on host to communication buffer copycbuftotmem() ... copies from communication buffer to memory on host copytmemtocbuf() ... copies from memory on host to communication buffer
chapter 1 overview application note u14371ej1v0an00 14 (4) host api management functions the following host api management functions are provided for enabling smooth host api system use. loadinformationfile() ... loads information file showinfocontentsall() ... displays contents information getversion() ... displays version information hextobuf() ... buffers hex file 1.2 outline of bios functions the host api system provides the following bios functions. for further information on bios functions, refer to chapter 7 bios functions . echoword: ... action corresponding to hi interrupt upon failure to establish communication route interpreter: ... specifies action corresponding to hi interrupt selpcmd: ... specifies jump destination function address puttocmdbuf: ... jumps upon occurrence of hi interrupt the specified number of times idtagcmd: ... jumps to specified user defined function reboot: ... performs reboot according to called address direct_rx: ... reads 1 data from x memory direct_ry: ... reads 1 data from y memory direct_wx: ... writes 1 data to x memory direct_wy: ... writes 1 data to y memory copy_xtox: ... copies data in x memory copy_ytoy: ... copies data in y memory copy_xtoy: ... copies data from x memory to y memory copy_ytox: ... copies data from y memory to x memory readfromcbuf:... reads data from write communication buffer writetocbuf: ... writes data to read communication buffer
application note u14371ej1v0an00 15 chapter 2 host api configuration this chapter explains the configuration of the host api system. 2.1 software configuration the host api system consists of api functions, which exist on the host processor and form the interface between the user application and the dsp, and bios functions, which exist on the dsp and consist of the actual host api functions. reboot, data memory access, and task management, among other things, are performed by passing data between these two codes. figure 2-1 shows an image of the software configuration. figure 2-1. software configuration image remark the host processor in the above figure is assumed to be a personal computer. the api functions are provided as c language functions, and are used by issuing a call to the user application, which is the center of control. the api function for which a call is issued to the user application issues a command to the dsp to realize that function. the bios functions are provided as m pd77016 family assembly language functions. which function is called is determined according to the result of decoding the commands issued by api functions. RX77016 target system dsp instruction memory bios task task data memory host processor application info/hex file api data communication data memory access task management reboot . . . hex file upload
chapter 2 host api configuration application note u14371ej1v0an00 16 in this application note, api functions are expressed by appending "()" to indicate the fact that they are c language function, and bios functions are expressed by appending ":" to indicate that they are upd77016 assembly language level. example api function "opendev" ? "opendev()" bios function "echoword" ? "echoword:" (1) api functions api functions consist of the following 6 files. the user application that calls an api function is compiled by the c compiler, and an execution file can be created by linking with the mos_hapi.c and spx.c object files (which must be compiled beforehand). hostapi.h ... header file required when a user application calls an api application hapiucfg.h ... header file for user definition of mos_hapi.c, spx.c mos_hapi.h ... header file of mos_hapi.c mos_hapi.c ... source file of api function spx.h ... header file of spx.c spx.c ... source file of interface block between api function and dsp (2) bios functions bios functions consist of the following 4 files. an executable file can be created by linking with the bios_fns.asm object file (which must be assembled beforehand) following insertion of the required code to the initialization block (_mos_targetsysinit:) for the target system of the RX77016 and the hi interrupt handler code block (_mos_ivhi:) (refer to 8.2.3. hi interrupt handler code block (_mos_ivhi:) and assembly in wb77016. bios_fns.h ... header file for target system initialization block (_mos-targetsysinit:) and hi interrupt handler code block (_mos_ivhi:) of RX77016 bios_mac.h ... macro definition file for target system initialization block (_mos_targetsysinit:) and bios_fns.asm of RX77016 biosucfg.h ... header file for target system initialization block (_mos_targetsysinit:) and hi interrupt handler code block (_mos_ivhi:) and bios_fns.asm of RX77016 bios_fns.asm ... source file of bios function
chapter 2 host api configuration application note u14371ej1v0an00 17 2.2 hardware configuration in the host api system, control is performed from the host processor (personal computer or microcontroller such as v85x) toward a dsp consisting of a single device. however, the host api system is designed to enable transition to a new version without changing the user program, when upgrading the version of the host api system while realizing multiple device support for RX77016 in the future. data communication is performed between the i/o port of the host processor and the host interface of the dsp note . when the i/o port address that is used is described in the io resources section of the information file, which is a host api information file (refer to 4.1 information file ), it is acquired by the loadinformationfile() and stored in a buffer. api functions that perform some kind of communication with the dsp, use this buffer information for data communication. figure 2-2 shows an image of the hardware configuration. note if the bios function of the host api is loaded to the dsp, other applications cannot use the hdt register, in order to acquire the host data register (hdt register). in host api, it is assumed that all data communication between the host processor and dsp are performed via the host api. figure 2-2. hardware configuration image remark the host processor in the above figure is assumed to be a personal computer. target system dsp bios hdt host processor information file application api hst rst table for i/o port address port port port
chapter 2 host api configuration application note u14371ej1v0an00 18 the host data register (hdt register) and host interface status register (hst register), which form the dsp host interface, can be accessed with either of two methods, byte access or word access note . byte access is done by dividing 16 bits (1 word) into higher 8 bits and lower 8 bits, and using a different i/o port for each to read/write data. word access is done through data read/write of 16 bits (1 word) using a single i/o port. figure 2-3 shows the image of byte access. note to switch the access method by condition compilation through definition of hdtaccess, hstaccess, and rstaccess of hapiucfg.h, a second compilation is required. figure 2-3. byte access image remark the host processor in the above figure is assumed to be a personal computer. target system dsp bios host processor application api rst information file table for i/o port address port port port port port hdt high byte low byte low byte hst high byte
application note u14371ej1v0an00 19 chapter 3 host api functions this chapter describes the functions of the host api system. 3.1 opening and closing communication path in the host api system, data communication with the dsp can be performed until a communication path with a particular dsp is opened through opendev() and then closed through closedev(). opendev() allocates a device handle corresponding to a particular dsp upon opening of a communication path. all the api functions use device handles to perform data communication with particular dsps. figure 3-1 shows the image of communication path opening and closing when r77016 and host api support multiple devices. figure 3-1. image of communication path opening and closing (support of multiple devices) remark the host processor in the above figure is assumed to be a personal computer. caution although this function will become truly valuable when the RX77016 supports multiple devices in the future, this function exists in the current version in order to minimize changes in user programs when this support is realized (this version of host api does not support multiple devices). target system dsp1 dsp2 dsp3 host processor application opendev(1) opendev(3) closedev(1) closedev(3) communication is enabled separately with dsp1 or dsp3 during this time control flow
chapter 3 host api functions application note u14371ej1v0an00 20 3.2 data setting to os communication area in the host api system, any desired data can be set to the RX77016's os communication area (*_mos_spx_pause:x) using setcommunicatevalue(). through this, it is possible to pause note following the startup of the RX77016 system. data setting to the os communication area is required when any kind of data communication is performed from external by a future RX77016 or individual applications. figure 3-2 shows the image of data setting to the os communication area. note pause following the startup of the RX77016 system refers to the state in which the execution of the next processing (application program start) is held until all the initialization processing of the os are completed and an instruction is received from external (such as from the host processor). pause is performed when *_mos_spx_pause:x is 0xffff, and when another value is written, pause is released. however, if a value other than 0xffff is written for the initial state, pause is not implemented and the next processing is performed. figure 3-2. image of data setting to os communication area remark the host processor in the above figure is assumed to be a personal computer. target system dsp host processor application setcommunicate value() instruction memory bios set x memory _mos_spx_pause: data
chapter 3 host api functions application note u14371ej1v0an00 21 3.3 reboot in the host api system, it is possible to perform x-word reboot, x-byte reboot, y-word reboot, y byte reboot, and host reboot, using the reboot subroutine of the dsp reboot rom with rebootdev(). moreover, it is also possible to use an extension intel hex file as the data source by using the hextobuf() function for host reboot (however, this is possible only when a personal computer is used as the host processor). figure 3-3 shows the reboot image. figure 3-3. reboot image remark the host processor in the above figure is assumed to be a personal computer. target system dsp instruction memory boot rom reboot area data memory host processor ex. intel hex file application rebootdev() call host boot reboot subroutine call buffer for reboot data bios call self boot
chapter 3 host api functions application note u14371ej1v0an00 22 3.4 data memory access in the host api system, it is possible to read/write data to any address in data memory, copy data within the same memory, and copy data between different memories using readfromtmem(), writetomem(), copytmemtohost(), copyhosttotmem(), or copytmemtotmem(). moreover, with copyhosttotmem(), it is also possible to use an extension intel hex file as the data source by using the hextobuf() function (however, this is possible only when a personal computer is used as the host processor). figure 3-4 shows the data memory access image. figure 3-4. data memory access image remark the host processor in the above figure is assumed to be a personal computer. x data memory y data memory target system dsp instruction memory bios host processor ex. intel hex file application memory access function call data read buffer for init data data write copy within the same memory copy within the same memory copy between different memories
chapter 3 host api functions application note u14371ej1v0an00 23 3.5 communication buffer in the host api system, it is possible to perform data communication between a user application and an application on the dsp by creating areas called communication buffers on the x or y memory of the dsp. there are two types of communication buffers, a write communication buffer used to transfer data from the user application to the application on the dsp, and a read communication buffer used to transfer data from the application on the dsp to the user application. the size note of these buffers can be freely set by the user. moreover, the communication buffers can perform data communication to any address in x or y data memory. figure 3-5 shows the image of the communication buffers. note the communication buffer size is set by defining hicbuf_heap_size and hocbuf_heap_size of biosucfg.h. figure 3-5. communication buffer image remark the host processor in the above figure is assumed to be a personal computer. x or y data memory target system dsp instruction memory bios host processor application communication buffer access function call data write buffer for communication data data read application write communication buffer read communication buffer data write data read
chapter 3 host api functions application note u14371ej1v0an00 24 3.5.1 securing and releasing communication buffer area it is possible to secure and release the area to be used in small increments as required within previously secured note heap areas (separate heap area for read and for write). each area to be used is secured with createcbuf() and released with freecbuf(). the range can be freely set when securing the area to be used with createcbuf(), as long as the sum of the size already secured and the newly secured size does not exceed the remaining heap area size, and the number of already secured buffers + 1 does not exceed the planned number of buffers. moreover, when securing an area, the handle corresponding to the area that is being secured is assigned. later, this handle is used to access specific areas. figure 3-6 shows image of securing the communication buffer areas. note the required area is automatically secured by defining hicbuf_heap_size, num_hicbuf, hocbuf_heap_size, and num_hocbuf to perform assembly. figure 3-6. image of securing communication buffer area remark the host processor in the above figure is assumed to be a personal computer. x or y data memory target system dsp instruction memory bios create host processor application <1>createcbuf (write buffer) call <2>createcbuf (write buffer) call <3>createcbuf (write buffer) call <4>createcbuf (write buffer) call <5>createcbuf (write buffer) call write communication buffer heap area read communication buffer heap area <1>, <3>, <5>: write communication buffer <2>, <4>: read communication buffer empty <1> <3> <5> empty <2> <4>
chapter 3 host api functions application note u14371ej1v0an00 25 when area release is performed with freecbuf(), the existing usage area is released and changes into a reusable area. moreover, after the area is released, memory compaction is performed so that the usage area is placed continuously from the start of the heap area. for example, when usage area <2> in figure 3-7 is released, a blank results between <1> and <3>, so that the position of <3> is changed so as to fill the position that was occupied by <2>. figure 3-7 shows the image of releasing a usage area. figure 3-7. image of releasing usage area remark the host processor in the above figure is assumed to be a personal computer. x or y data memory target system dsp instruction memory bios free host processor application freecbuf(<2>) call write communication buffer heap area <3> is shifted to fill position that was occupied by <2> after <2> is released. empty <1> <2> <3> <1> <3> empty
chapter 3 host api functions application note u14371ej1v0an00 26 3.5.2 communication buffer access communication buffers can be accessed in two ways: access from an api function, and access from an application on the dsp. in the case of access from an api application, one of initcbuf(), readfromcbuf(), writetocbuf(), copycbuftohost(), copyhosttocbuf(), copycbuftotmem(), or copytmemtocbuf() is called, and in the case of access from an application on the dsp, readfromcbuf: or writetocbuf: is called (for additional information on there functions, refer to chapter 6 api functions and chapter 7 bios functions ). figure 3-8 shows the image of communication buffer access (in the case where <2> is current). figure 3-8. image of communication buffer access remark the host processor in the above figure is assumed to be a personal computer. x or y data memory target system dsp instruction memory bios access host processor application communication buffer access function call data read data write data read data write application call write communication buffer read communication buffer access from api function <1> <1> <2> <2> <3> <3> <4> <4> access from application on dsp data read data write
chapter 3 host api functions application note u14371ej1v0an00 27 the basic access procedure for the write communication buffer is as follows. <1> secure the usage area with createcbuf(). <2> write data to the usage area secured in step <1> with initcbuf(), writetocbuf(), copyhosttocbuf(), or copytmemtocbuf(). <3> read the data of the usage area to which data has been written in step <2> with copycbuftotmem() or readfromcbuf:. the basic access procedure for the read communication buffer is as follows. <1> secure the usage area with createcbuf(). <2>write data to the usage area secured in step <1> with copytmemtocbuf() or writetocbuf():. <3> read the data of the usage area to which data has been written in step <2> with readfromcbuf(), copycbuftohost(), or copycbuftotmem(). however, due to the nature of the communication buffers, there may be accessible at times and not at other times. communication buffer accessibility is summarized in the following table. table 3-1. list of communication buffer access states write communication buffer read communication buffer state of usage buffer function written data is read written data is not read written data is read written data is not read initcbuf() accessible not accessible access prohibited access prohibited readfromcbuf() access prohibited access prohibited not accessible accessible writetocbuf() accessible not accessible access prohibited access prohibited copycbuftohost() access prohibited access prohibited not accessible accessible copyhosttocbuf() accessible not accessible access prohibited access prohibited copycbuftotmem() not accessible accessible not accessible accessible copytmemtocbuf() accessible not accessible accessible not accessible readfromcbuf: not accessible accessible access prohibited access prohibited writetobuf access prohibited access prohibited accessible not accessible when an api function or bios function attempts to access a communication buffer that is not accessible, an error value is returned as the return value, and it is possible to decide the next processing based on this value.
chapter 3 host api functions application note u14371ej1v0an00 28 3.6 task management in the host api system, an operating task can be changed to a stopped task, and a stopped task can be changed to an operating task by using suspendsynctask() and resumesynctask(). "0" is set to the frame counter a note of the specified task by suspendsynctask(). if the value of the frame counter prior to setting was other than 0, the change that is made is from an operating task to a stopped task. the value specified with the taskstate key of the subtaskxxyy section of the information file is set to frame counter a of the frame clock table of RX77016. if the value of frame counter a was 0, the change that is made is from a stopped task to an operating task. figure 3-9 shows the image of task management. note this value is the calculation value for the frame counter value. the timer is referenced for the calculation, and the calculation is performed during a fixed cycle. (for details, refer to RX77016 user's manual functions .) figure 3-9. task management image remark the host processor in the above figure is assumed to be a personal computer. x or y data memory target system dsp instruction memory bios set0 set taskstate value host processor application suspendsync task() call frame clock table frame counter frame counter a frame counter b resumesync task() call
application note u14371ej1v0an00 29 chapter 4 input files 4.1 information files the host api loads up information files to obtain i/o port addresses, communication buffer information, task information, and so on. information files are in the windows ini format, and are defined with the following sections and keys. 4.1.1 device section (1) specification of device identifier devicedescription key specify the device identifier with 31 characters or less (2-byte characters are counted as 2 character). the identifier specified here becomes the target device name when changing the bios to a communication enabled mode (opendev() call). characters over the 32nd character are truncated if a device identifier longer than 32 characters is specified. in the following example, "spx0" is specified as the device identifier. devicedescription = spx0 4.1.2 io resource section (1) specification of i/o port address of hdt register depending on whether byte access or word access of the hdt register is performed, both the ioporthdtlow and ioporthdthigh keys, or the ioporthdt key is used. ioporthdtlow, ioporthdthigh keys specify the i/o port address when performing byte access of the hdt register with 4 or fewer hexadecimal digits. specify hdt register bits 0 to 7 to ioporthdtlow, and i/o port address bits 8 to 15 to ioporthdthigh. in the following description example, 0x8020 is specified to ioporthdtlow, and 0x8021 is specified to ioporthdthigh. ioporthdtlow = 0x8020 ioporthdthigh = 0x8021 ioporthdt key specify the i/o port address when performing word access of the hdt register with 4 or fewer hexadecimal digits. ioporthdtlow key definitions and ipoporthdthigh key definitions become invalid after the ioporthdt key. in the following description example, 0x8020 is specified to ioporthst. ioporthdt = 0x8020
chapter 4 input files application note u14371ej1v0an00 30 (2) specification of i/o port address of hst register depending on whether byte access or word access of the hst register is performed, both the ioporthstlow and ioporthsthigh keys, or the ioporthst key is used. ioporthstlow, ioporthsthigh keys specify the i/o port address when performing byte access of the hst register with 4 or fewer hexadecimal digits. specify hst register bits 0 to 7 to ioporthstlow, and i/o port bits 8 to 15 to ioporthsthigh. in the following description example, 0x8022 is specified to ioporthstlow, and 0x8023 is specified to ioporthsthigh. ioporthstlow = 0x8022 ioporthsthigh = 0x8023 ioporthst key specify the i/o port address when performing word access of the hst register with 4 or fewer hexadecimal digits. in the following description example, 0x8022 is specified to ioporthst. ioporthst = 0x8022 (3) specification of i/o port address for rst pin access depending on whether byte access or word access of the i/o port is performed, both the ioportrstlow and ioportrsthigh keys, or the ioportrst key is used. ioportrstlow, ioportrsthigh keys specify the i/o port when performing byte access of the i/o port for rst pin access in 4 or fewer hexadecimal digits. specify bits 0 to 7 of the word including the rst pin to ioportrstlow, and bits 8 to 16 to ioportrsthigh. in the following example, 0x8024 is specified to ioportrstlow, and 0x8025 is specified to ioportrsthigh. ioportrstlow = 0x8024 ioportrsthigh = 0x8025 ioportrst key define the i/o port address when performing word access of the i/o port for rst pin access with 4 or fewer hexadecimal digits. in the following description example, 0x8024 is specified to ioportrst. ioportrst = 0x8024
chapter 4 input files application note u14371ej1v0an00 31 (4) specification of rst pin bit assign depending on whether byte access or word access of the i/o port is performed, both the ioportrstlow and ioportrsthigh keys, or the ioportrst key is used. bitassignrstlow, bitassignrsthigh keys specify the bit position of the rst pin when performing byte access of the i/o port for rst pin access as 2 or fewer hexadecimal digits. specify bit assign of bits 0 to 7 of the word including the rst pin to bitassignrstlow, bits bit assign of bits 8 to 15 to bitassignrsthigh. specify 1 for the corresponding position, and 0 for other positions. in the following example, 0x01 is specified to bitassignrstlow, and 0x00 is specified to bitassignrsthigh. bitassignrstlow = 0x01 bitassignrsthigh = 0x00 bitassignrst key specify the bit position of the rst pin when performing word access of the i/o port for rst pin access as 4 or fewer hexadecimal digits. specify 1 for the corresponding position, and 0 for other positions. in the following example, 0x0001 is specified to bitassignrst. bitassignrst = 0x0001 (5) mask data of i/o port for rst pin access depending on whether byte access or word access of the i/o port for rst pin access is performed, both the maskdatarstlow and maskdatarsthigh keys, or the maskrst key is used. maskdatarstlow, maskdatarsthigh keys specify the or mask data of other than the rst pin when performing byte access of the i/o port for rst pin access as 2 or fewer hexadecimal digits. specify bits 0 to 7 of the word including the rst pin to maskdatarstlow, and bits 8 to 15 of the mask data to maskdatarsthigh (in the case of access to the rst pin, masking is not performed even if 1 is set to the rst pin bit position). in the following description example, 0x30 is specified to maskdatarstlow, and 0x05 is specified to maskdatarsthigh. maskdatarstlow = 0x30 maskdatarsthigh = 0x05 maskdatarst key specify the or mask data of other than the rst pin when performing word access of the i/o port for rst pin access as 4 or fewer hexadecimal digits (in the case of access to the rst pin, masking is not performed even if 1 is set to the rst pin bit position). in the following description example, 0x3005 is specified to maskdatarst. maskdatarst = 0x3005
chapter 4 input files application note u14371ej1v0an00 32 4.1.3 task section (1) specification of number of tasks ntask key specify the number of tasks controlled by the RX77016 on the target device as 4 or fewer decimal digits. in the following description example, 2 is specified for ntask. ntask = 2 4.1.4 taskxx section in the taskxx section, the number of sections specified with the ntask key must be described. continuous numbers starting from 01 are allocated to xx. if 3 is specified to the ntask key, 01 to 03 is allocated to xx, and the task01, task02, and task03 sections are described. moreover, taskxx must be indicated to the same task as taskx of the RX77016. (1) specification of number of subtasks nsubtask key specify the number of subtasks of taskx as 4 or fewer decimal digits. in the following description example, 1 is specified for nsubtask of task01, and 3 is specified for nsubtask of task02. [task01] nsubtask = 1 [task02] nsubtask = 3 4.1.5 subtaskxxyy section in the subtaskxxyy section, the number of sections specified with the nsubtask key must be described. the same value as for the taskxx section is allocated to xx. continuous numbers starting from 00 according to the number specified to the nsubtask key are allocated to yy. if 2 is specified to the ntask key of the task section, 2 is specified to the nsubtask key of the task01 section, and 3 is specified to the nsubtask key of the task02 section, 0100, 0101, 0200, 0201, and 0202 are allocated to xxyy, and the subtask0100, subtask0101, subtask0200, subtask0201, and subtask0202 sections are described. moreover, subtaskxxyy must be indicated to the same task as subtaskxy of the RX77016. (1) specification of subtask name taskname key specify the subtask name of subtaskxxyy as 31 or fewer characters. if the subtask name is specified as 32 or more characters, all characters past the 31st will be cut off. in the following description example, "swapio" is specified to the taskname of the subtask0101 section. [subtask0101] taskname = swapio
chapter 4 input files application note u14371ej1v0an00 33 (2) specification of subtask state taskstate key specify the subtask state note of subtaskxxyy as 4 or fewer hexadecimal digits. in the following description example, 1 is specified to taskstate of the subtask0101 section. [subtask0101] taskstate = 1 note value set by resumesynctask() to frame counter a of the frame clock table. 4.1.6 information file description example figure 4-1 shows a description example of an information file. figure 4-1. information file description example ;********************************************************** ;* upd77016 series processor information file for example * ;********************************************************** [device] devicedescription=spx0 [io resource] ioporthdt=0x8020 ioporthst=0x8022 ioportrst=0x8024 bitassignrst=0x0001 maskdatarst=0x3005 [task] ntask =2 [task01] nsubtask=1 [task02] nsubtask=3 [subtask0100] taskname=swapio taskstate=1 [subtask0200] taskname=reverb taskstate=1 [subtask0201] taskname=chorus taskstate=1 [subtask0202] taskname=surround taskstate=1
chapter 4 input files application note u14371ej1v0an00 34 4.2 hex file when rebooting instructions or data, host api must accumulate load data beforehand in a buffer for the dsp. an extension intel hex file (such as .hxi, .hdx, or .hdy files, which are output by the wb77016) can be specified as that data source. in the host api system, the api function to accumulate the extension intel hex file data source to the specified buffer is supported. figure 4-2 shows the image of reboot using an extension intel hex file. figure 4-2. image of reeboot using extension intel hex file remark the host processor in the above figure is assumed to be a personal computer. data memory target system dsp instruction memory bios host processor application api call data memory initialization host reboot reboot area buffer for reboot data ex. intel hex file
application note u14371ej1v0an00 35 chapter 5 host api system 5.1 bios mode there are two bios modes, the communication enabled mode and the communication disabled mode. the communication enabled mode is a mode that enables communication to be performed freely between api applications and bios applications. when communication is not possible, a communication path is established by calling opendev(), and the mode changes to the communication enabled mode. at this time, the bios function that has received the hdt register data written by the api function judges this data as a command or a parameter, and performs the appropriate processing. the communication disabled mode is a mode in which communication between api functions and bios functions cannot be performed. when communication is possible, the communication path is closed by calling closedev() and the mode changes to the communication disabled mode. the bios initial status is the communication disabled mode. at this time, the data written to the hdt register is judged to be meaningless, and it is not decoded. figure 5-1 shows the change of the bios mode when the user application calls opendev() and the closedev(). figure 5-1. change in bios mode when calling opendev(), closedev() user application loadinformationfile() opendev() host processor ? dsp communication start closedev() end start communication disable mode communication enable mode communication disable mode
chapter 5 host api system application note u14371ej1v0an00 36 5.2 bios function call in the host api system, all api functions except for the host api management functions send commands and parameters to the dsp in order to call the bios functions that realize functions. commands refer to codes for calling the desired bios function, and by decoding these commands, it is possible to determine the function to be called and the required parameters. parameters refer to the data required when calling a function corresponding to a command. for example, the write address and write data for memory write are two such parameters. the bios performs a bios function call when the required number of parameters is obtained when it stacks parameters in the stack area called command buffer. figure 5-2 shows the operation flow of the bios kernel. figure 5-2. bios kernel operation flow bios operation command reception command decoding parameter stacking end start parameter reception all required parameters obtained? bios function call yes no
37 application note u14371ej1v0an00 chapter 6 api functions 6.1 data definition the data types shown in table 6-1 are defined for api functions. table 6-1. data types defined data type c language expression data type application byte unsigned char unsigned 1-byte data lpbyte unsigned char* unsigned 1-byte data pointer sword short signed 2-byte data word unsigned short unsigned 2-byte data lpword unsigned short* unsigned 2-byte data pointer dword unsigned long unsigned 4-byte data devhnd unsigned short device handle cbhnd unsigned short cb handle lpcbhnd unsigned short far* cb handle pointer subtaskinfo typedef struct { word id ; byte name[max_names] ; word framesubvalue ; word framesubaddress ; } subtaskinfo ; subtask id subtask name framesub value framesub address rebootparam typedef struct { word cmdid ; word numinstsize ; word srcstaraddr ; word *srcpointer ; word deststartaddr ; } rebootparam ; reboot command id boot size source start address (during self boot) source pointer (during host boot) destination start address cbcaps typedef struct { word startaddr ; word nsize ; word rwflag ; dword structaddr ; } cbcaps ; cb start address cb size cb r/w flag cb information address remark cb: communication buffer
chapter 6 api functions 38 application note u14371ej1v0an00 the following character constants are defined for api functions. table 6-2. character constants defined constant string c language expression data application success (sword)0x0000 api function return value file_notfound (sword)0xfff5 api function return value subtasktbl_full (sword)0xfff6 api function return value cbtbl_full (sword)0xfff7 api function return value cb_full (sword)0xfff8 api function return value cb_empty (sword)0xfff9 api function return value funcid_error (sword)0x fffa api function return value already_open (sword)0xfffb api function return value cbhnd_error (sword)0x fffc api function return value devhnd_error (sword)0x fffd api function return value devname_error (sword)0xfffe api function return value fail (sword)0xffff api function return value _mha_selpcmd_cmd 0x8000 command id _mha_idtagcmd_cmd 0x4000 command id _mha_reboot_subcmd 0x0000 sub-command id _mha_direct_rx_subcmd 0x0002 sub-command id _mha_direct_ry_subcmd 0x0004 sub-command id _mha_direct_wx_subcmd 0x0006 sub-command id _mha_direct_wy_subcmd 0x0008 sub-command id _mha_copy_xtox_subcmd 0x000a sub-command id _mha_copy_ytoy_subcmd 0x000c sub-command id _mha_copy_xtoy_subcmd 0x000e sub-command id _mha_copy_ytox_subcmd 0x0010 sub-command id _mha_reboot_host_cmd 0x0005 reboot command id _mha_reboot_x_byte_cmd 0x0004 reboot command id _mha_reboot_y_byte_cmd 0x0003 reboot command id _mha_reboot_x_word_cmd 0x0002 reboot command id _mha_reboot_y_word_cmd 0x0001 reboot command id read 0x0000 r/w flag write 0x0001 r/w flag cb_notused 0xffff cb usage status flag wait 0x0000 cb access restriction flag non_wait 0x0001 cb access restriction flag inst 0x0000 hex file judgment flag data 0x0001 hex file judgment flag remark cb: communication buffer
chapter 6 api functions 39 application note u14371ej1v0an00 6.2 api application functions 6.2.1 initial setting functions (1) opendev() [description] establishes a communication path to the device set to dev_name and writes that device handle to the device. sword opendev( devhnd *device /* device handle storage destination pointer */ lpbyte dev_name /* target device name pointer */ ); when this function is called, the bios goes into the communication enabled mode. when an api function is used to perform some data communication with a target device, this function must be called beforehand. dev_name describes the device name specified with the devicedes key of the device section of the information file. this function will display its worth when the host api supports multiple devices in the future. it is included in the current version in order to minimize user program changes once the host api starts supporting multiple devices. [return value] success ... communication path was successfully established. devname_error ... a device name that cannot be recognized has been specified. already_open ... the specified device is already open. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ){ puts(it failed to open device.) ; return -1 ; } if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 40 application note u14371ej1v0an00 (2) closedev() [description] closes the communication path with the target device. sword closedev( devhnd device /* target device handle */ ); when this function is called, the bios goes into the communication disabled mode. this function is used when the api, which performs some data communication with a target device, is not used further. this function will display its worth when the host api supports multiple devices in the future. it is included in the current version in order to minimize user program changes once the host api starts supporting multiple devices. [return value] success ... communication path was successfully closed. devhnd_error ... a device handle that cannot be recognized has been specified. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(closedev(device1)!=success){ puts(it failed to close device.) ; return -1 ; } return 0; }
chapter 6 api functions 41 application note u14371ej1v0an00 (3) rebootdev() [description] performs x word/byte reboot, y word/byte reboot, or self boot for the target device. sword rebootdev( devhnd device, /* target device handle */ rebootparam*spxrbtparam /* rebootparam structure pointer */ ); when host boot is performed using this function, it is necessary to accumulate boot data in the buffer with head address spxrbtparam ? srcstartaddr. if an extension intel hex file is used as the data source, the hextobuf() function can be used to perform buffering. [return value] success ... reboot was successful. devhnd_error ... a device handle that cannot be recognized has been specified. fail ... communication with the dsp failed. [code example] word ibuff[]={ 0x0000,0x0000,0x0000,0x0000 } ; rebootparam rebootparam1={ _mha_reboot_host_cmd, // reboot function id 2, // size of reboot instruction 0, // start address of source ibuff, // pointer of source 1024, // start address of destination } ; int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(rebootdev(device1,&rebootparam1)!=success){ puts(it failed to reboot device.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 42 application note u14371ej1v0an00 (4) resetdev() [description] performs system reset for the target device. sword resetdev( devhnd device /* target device handle */ ); [return value] success ... system reset was successful. devhnd_error ... a device handle that cannot be recognized has been specified. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return C1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(resetdev(device1)!=success){ puts(it failed to reset device.) ; return -1 ; } return 0; }
chapter 6 api functions 43 application note u14371ej1v0an00 (5) setcommunicatevalue() [description] sets the data specified to the os communication area (*_mos_spx-pause:x) of the RX77016. sword setcommunicate value( devhnd device, /* target device handle */ word value /* setting data */ ); [return value] success ... setting was successful devhnd_error ... a device handle that cannot be recognized has been specified. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success){ puts(it failed to set communicate value.) ; return -1 ; } if(closedev(device)!=success) return -1 ; return 0; }
chapter 6 api functions 44 application note u14371ej1v0an00 6.2.2 task management functions (1) showtask() [description] shows the task information loaded up with the loadinformationfile(). if return_to_window is defined, the information is displayed in the message box on windows. if return_to_window is not defined, the information is displayed on the console, and the func structure pointer is copied to pfunc. sword showtask( devhnd device, /* target device handle */ word subtaskid, /* subtask id */ subtaskinfo*psubtask /* func structure copy destination pointer */ ); the displayed items consist of the subtask name, subtask id, current state, and frame counter a. [return value] success ... display was successful devhnd_error ... a device handle that cannot be recognized has been specified. funcid_error ... a subtask id that cannot be recognized has been specified. [code example] int main() { func func1 ; devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(showtask(&device1,100,&func1)!=success ){ puts(it failed to show task information.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 45 application note u14371ej1v0an00 (2) resumesynctask() [description] writes the devinf[device].subtask[subtaskid]->framesubvalue value to frame counter a of the frame clock table of the RX77016 that corresponds to the specified task. if a value other than 0 is written when the original frame counter a value is 0, that task becomes an executable task. sword resumesynctask( devhnd device, /* target device handle */ word subtaskid /* subtask id */ [return value] success ... update of the frame counter a value was successful devhnd_error ... a device handle that cannot be recognized has been specified. funcid_error ... a subtask id that cannot be recognized has been specified. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(resumesynctask(device1,100)!=success ){ puts(it failed to resume task.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 46 application note u14371ej1v0an00 (3) suspendsynctask() [description] writes 0 to frame counter a of the frame clock table of the RX77016 that corresponds to the specified task. if the original frame counter a value is other than 0, that task becomes a stopped task. sword suspendsynctask( devhnd device, /* target device handle */ word subtaskid /* subtask id */ ); [return value] success ... update of the frame counter a value was successful devhnd_error ... a device handle that cannot be recognized has been specified. funcid_error ... a subtask id that cannot be recognized has been specified. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(suspendsynctask(device1,100)!=success ){ puts(it failed to suspend task.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 47 application note u14371ej1v0an00 6.2.3 memory access functions (1) createcbuf() [description] creates an nsize used area from the communication buffer heap area previously secured. moreover, allocates a communication buffer handle that corresponds to the prepared used area. sword createcbuf( devhnd device, /* target device handle */ word nsize, /* communication buffer size */ word rwflag, /* r/w flag */ cbhnd*cbuf /* communication buffer handle storage destination pointer */ ); if the nsize value is larger than the remaining heap area, or if the planned number of buffers is exceeded, no new area is created. "read" or "write" is specified for rwflag, in the case of the read communication buffer and in the case of the write communication buffer, respectively. [return value] success ... creation was successful devhnd_error ... a device handle that cannot be recognized has been specified. cbhnd_error ... the number of buffers specified with biosucfg.h has been exceeded. cbtbl_full the number of buffers specified with hapiucfg.h has been exceeded. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; cbhnd cbhnd1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(createcbuf(device1,10,read,&cbhnd1)!=success ){ puts(it failed to create communication buffer.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 48 application note u14371ej1v0an00 (2) freecbuf() [description] releases the used areas of the communication buffer that have become unnecessary. sword freecbuf( devhnd device, /* target device handle */ cbhnd cbuf /* communication buffer handle releasing area */ ); [return value] success ... area was successfully released devhnd_error ... a device handle that cannot be recognized has been specified. cbhnd_error ... a communication buffer handle that cannot be recognized has been specified. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; cbhnd cbhnd1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(createcbuf(device1,10,read,&cbhnd1)!=success ){ puts(it failed to create communication buffer.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 49 application note u14371ej1v0an00 (3) getcbufcaps() [description] copies communication buffer information to the cbcaps structure. if return_to_window is defined, displays this information to the message box on windows. sword getcbufcaps( devhnd device, /* target device handle */ cbhnd cbuf, /* target communication handle */ cbcaps *pcommbufcaps /* cbcaps structure copy destination pointer */ [return value] success ... copy or display was successful. devhnd_error ... a device handle that cannot be recognized has been specified. cbhnd_error ... a communication buffer handle that cannot be recognized has been specified. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; cbcaps cbcaps2 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(createcbuf(device1,10,read,&cbhnd1)!=success ) return -1 ; if(getcbufcaps(device1,cbhnd1,&cbcaps2)!=success){ puts(it failed to get communication buffer capabilities.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 50 application note u14371ej1v0an00 (4) initcbuf() [description] clears to 0 the contents of the specified used area of the write communication buffer. sword initcbuf( devhnd device, /* target device handle */ cbhnd cbuf /* target communication buffer handle */ ); if the data written previously has not yet been read, this function returns cb_full and clearing cannot be performed. [return value] success ... clearing to 0 was successful. devhnd_error ... a device handle that cannot be recognized has been specified. cbhnd_error ... a communication buffer handle that cannot be recognized has been specified. cb_full ... previously written data has not been read. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(createcbuf(device1,10,write,&cbhnd1)!=success ) return -1 ; if(initcbuf(device1,cbhnd1)!=success ){ puts(it failed to initialize communication buffer.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 51 application note u14371ej1v0an00 (5) readfromtmem() [description] writes the srcaddr address data of the data memory on the target device to the iprdata address of the memory on the host processor. sword readfromtmem( devhnd device, /* target device handle */ dword srcaddr, /* source address (srcaddr+0x10000 in case of ymem) */ lpword iprdata /* read data write destination pointer */ ); in the case of read from x memory, specify the address as is, and in the case of read from y memory, specify address + 0x10000 for srcaddr. [return value] success ... read was successful. devhnd_error ... a device handle that cannot be recognized has been specified. fail ... communication with the dsp failed, or a parameter is abnormal. [code example] int main() { devhnd device1 ; unsigned short rdata ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(readfromtmem(device1,0x10000,&rdata)!=success ){ puts(it failed to read data .) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 52 application note u14371ej1v0an00 (6) writetomem() [description] writes wdata to the destaddr address of the data memory on the target device. sword writetotmem( devhnd device, /* target device handle */ dword destaddr, /* destination address (destaddr + 0x10000 in case of ymem) */ word wdata /* write data */ in the case of write to x memory, specify the address as is, and in the case of write to y memory, specify address + 0x10000 for destaddr. [return value] success ... write was successful. devhnd_error ... a device handle that cannot be recognized has been specified. fail ... communication with the dsp failed, or a parameter is abnormal. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(writetotmem(device1,0x0000,0x369c)!=success ){ puts(it failed to write data .) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 53 application note u14371ej1v0an00 (7) readfromcbuf() [description] writes the data of any address of the specified used area of the read communication buffer to the iprdata address of the memory on the host processor. sword readfromcbuf( devhnd device, /* target device handle */ cbhnd cbuf, /* target communication buffer handle */ word reladdr, /* read destination address */ lpword iprdata /* destination pointer */ word flag /* access restriction flag */ ); for the read destination address (reladdr), specify the number of the data in the specified used area that is to be read (refer to figure 6-1). figure 6-1. read communication buffer read destination address specify either wait or non_wait for the access restriction flag (flag). in the case of wait, data write using copytmemtocbuf() or writetocbuf: is not enabled. in the case of non_wait, data write using copytmemtocbuf() or writetocbuf: is enabled. for example, in the case of figure 6-1, it is possible to perform write upon reading 1 data even in used area 0 (size 4). to read all the data of size 4 used area, the following 4 steps are required. readfromcbuf(device,cbuf,0,rdata++,wait) ; readfromcbuf(device,cbuf,1,rdata++,wait) ; readfromcbuf(device,cbuf,2,rdata++,wait) ; readfromcbuf(device,cbuf,3,rdata++,non_wait) ; however, in the case of flag detection for readfromcbuf(), wait is judged in the case of a value other than 0, and non_wait is judged if the value is 0. therefore, the following description is possible if one uses the characteristics of the flag detection method. for(i=0 ; i<=3 ; i++) readfromcbuf(device,cbuf,i,rdata++,3-i) ; read communication buffer address to be read xxxx xxxx xxxx xxxx xxxx xxxx 0 1 used area 0 used area 1 2 3 0 1
chapter 6 api functions 54 application note u14371ej1v0an00 if all the current data has been read, this function returns cb_empty and read is not performed. [return value] success ... read was successful. devhnd_error ... a device handle that cannot be recognized has been specified. cbhnd_error ... a communication buffer handle that cannot be recognized has been specified. cb_empty ... the communication buffer contents have either been read or are empty. fail ... communication with the dsp failed, or a parameter is abnormal. [code example] int main() { devhnd device1 ; unsigned short rdata[10] ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(createcbuf(device1,10,read,&cbhnd1)!=success ) return -1 ; for(int i=9 ; i>=0 ; i--) { if(readfromcbuf(device1,cbhnd1,i,rdata++,i)!=success ){ puts(it failed to read communication buffers data.) ; } } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 55 application note u14371ej1v0an00 (8) writetocbuf() [description] writes wdata to any address in the specified used area of the write communication buffer. sword writetocbuf( devhnd device, /* target device handle */ cbhnd cbuf, /* target communication handle */ word reladdr, /* write destination address */ sword wdata /* write data */ word flag /* access restriction flag */ ); the write destination address (reladdr) specifies the number area of the specified used area to which data is to be written. (refer to figure 6-2 .) figure 6-2. write communication buffer write destination address specify either wait or non_wait for the access restriction flag (flag). in the case of wait, data read using copycbuftotmem() or readfromcbuf: is not enabled. in the case of non_wait, read using copycbuftotmem() or readfromcbuf: is enabled. when non_wait is set, it is possible to enable read upon write of 1 data, even in the case of used area 0 (size 4) mentioned above. to write all the data of size 4 used area, the following 4 steps are required. writetocbuf(device,cbuf,0,*wdata++,wait) ; writetocbuf(device,cbuf,1,*wdata++,wait) ; writetocbuf(device,cbuf,2,*wdata++,wait) ; writetocbuf(device,cbuf,3,*wdata++,non_wait) ; however, in the case of writetocbuf(), wait is judged in the case of a value other than 0 for flag detection, and non_wait is judged if the value is 0. therefore, the following description is possible if one uses the characteristics of the flag detection method. for(i=0 ; i<=3 ; i++) writetocbuf(device,cbuf,i,*wdata++,3-i) ; write communication buffer address to be written xxxx xxxx xxxx xxxx xxxx xxxx 0 1 used area 0 used area 1 2 3 0 1
chapter 6 api functions 56 application note u14371ej1v0an00 if some previously written data remains unread, this function returns cb_full and write is not performed. [return value] success ... read was successful. devhnd_error ... a device handle that cannot be recognized has been specified. cbhnd_error ... a communication buffer handle that cannot be recognized has been specified. cb_full ... previously written data has not been read. fail ... communication with the dsp failed, or a parameter is abnormal. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(createcbuf(device1,10,write,&cbhnd1)!=success ) return -1 ; for(int i=9 ; i>=0 ; i--){ if(writetocbuf(device1,cbhnd1,i,0x369c,i)!=success ){ puts(it failed to write data to communication buffer.) ; } } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 57 application note u14371ej1v0an00 (9) copytmemtohost() [description] copies srcaddr + nsize - 1 address data from the srcaddr address of data memory on the target device from the destptr of memory on the host processor to the destptr + nsize - 1 address area. sword copytmemtohost( devhnd device, /* target device handle */ dword srcaddr, /* source address (srcaddr + 0x10000 in case of ymem) */ lpword destptr, /* destination pointer */ word nsize /* copy size */ ); in the case of copy from x memory, specify the address as is, and in the case of read from y memory, specify address + 0x10000 for srcaddr. [return value] success ... copy was successful. devhnd_error ... a device handle that cannot be recognized has been specified. fail ... communication with the dsp failed, or a parameter is abnormal. [code example] int main() { devhnd device1 ; unsigned short rdata[10] ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(copytmemtohost(device1,0x10000,rdata,0x10)!=success ){ puts(it failed to copy data.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 58 application note u14371ej1v0an00 (10) copyhosttotmem() [description] copies srcptr + nsize - 1 address data from the srcptr address of the memory on the host processor from the destaddr of memory on the target device to the destaddr + nsize - 1 address area. sword copyhosttotmem( devhnd device, /* target device handle */ lpword srcptr, /* source address */ dword destaddr, /* destination address (destaddr + 0x1000 in case of ymem) */ word nsize /* copy size */ ); in the case of copy to x memory, specify the address as is, and in the case of copy to y memory, specify address + 0x10000 for destaddr. [return value] success ... copy was successful. devhnd_error ... a device handle that cannot be recognized has been specified. fail ... communication with the dsp failed, or a parameter is abnormal. [code example] int main() { devhnd device1 ; unsigned short wdata[]={ 0,1,2,3,4,5,6,7,8,9 } ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(copyhosttotmem(device1,wdata,0x10000,10)!=success ){ puts(it failed to opendevice.) ; return -1 ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 59 application note u14371ej1v0an00 (11) copycbuftohost() [description] enables data write following copying of the specified used area data of the read communication buffer from the destptr address of memory on the host processor to the destptr+buffer size - 1 address area. sword copycbuftohost( devhnd device, /* target device handle */ cbhnd cbuf, /* target communication handle */ lpword destptr, /* destination pointer */ ); if all the current data has been read, this function returns cb_empty and read is not performed. [return value] success ... copy was successful. devhnd_error ... a device handle that cannot be recognized has been specified. cbhnd_error ... a communication buffer handle that cannot be recognized has been specified. cb_empty ... the communication buffer contents have either been read or are empty. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; word rdata[10] ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(createcbuf(device1,10,read,&cbhnd1)!=success ) return -1 ; if(copycbuftohost(device1,cbhnd1,rdata)!=success ){ puts(it failed to copy communication buffers data to host.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 60 application note u14371ej1v0an00 (12) copyhosttocbuf() [description] enables data read following copying of srcptr + buffer size - 1 address data from the srcptr address on memory on the host processor to the specified used area of the write communication buffer. sword copyhosttocbuf( devhnd device, /* target device handle */ cbhnd cbuf, /* target communication handle */ sword*srcptr /* source address */ if the previously written data has not yet been read, this function returns cb_full and write is not performed. [return value] success ... copy was successful. devhnd_error ... a device handle that cannot be recognized has been specified. cbhnd_error ... a communication buffer handle that cannot be recognized has been specified. cb_full ... previously written data has not been read. fail ... communication with the dsp failed. [code example] int main() { devhnd device1 ; unsigned short wdata[]={ 0,1,2,3,4,5,6,7,8,9 } ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(createcbuf(device1,10,write,&cbhnd1)!=success ) return -1 ; if(copyhosttocbuf(device1,cbhnd1,&wdata)!=success ){ puts(it failed to copy data to communication buffer.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 61 application note u14371ej1v0an00 (13) copycbuftotmem() [description] enables data write following copying of nsize data from the start of the specified used area of the read or communication buffer from the destaddr address of the memory on the same device to the destaddr + nsize - 1 address. sword copycbuftotmem( devhnd device, /* target device handle */ cbhnd cbuf, /* target communication handle */ dword destaddr, * destination address (destaddr + 0x10000 in case of ymem) word nsize /* copy size */ ); if all the current data has been read, this function returns cb_empty and read is not performed. [return value] success ... copy was successful. devhnd_error ... a device handle that cannot be recognized has been specified. cbhnd_error ... a communication buffer handle that cannot be recognized has been specified. cb_empty ... cb_empty ... the communication buffer contents have either been read or are empty. fail ... communication with the dsp failed, or a parameter is abnormal. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(createcbuf(device1,10,read,&cbhnd1)!=success ) return -1 ; if(copycbuftotmem(device1,cbhnd1,0x10000,10)!=success ){ puts(it failed to copy communication buffers data to memory.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 62 application note u14371ej1v0an00 (14) copytmemtocbuf() [description] enables data read following copying of srcaddr + nsize - 1 address data from the srcaddr address of memory on the target device from the start address of the specified used area of the read or write communication buffer. sword copytmemtocbuf( devhnd device, /* target device handle */ cbhnd cbuf, /* target communication handle */ dword srcaddr, /* source address (srcaddr + 0x10000 in case of ymem) */ word nsize /* copy size */ ); if the previously written data has not yet been read, this function returns cb_full and write is not performed. [return value] success ... copy was successful. devhnd_error ... a device handle that cannot be recognized has been specified. cbhnd_error ... a communication buffer handle that cannot be recognized has been specified. cb_full ... previously written data has not been read. fail ... communication with the dsp failed, or a parameter is abnormal. [code example] int main() { devhnd device1 ; unsigned short wdata[]={ 0,1,2,3,4,5,6,7,8,9 } ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(createcbuf(device1,10,write,&cbhnd1)!=success ) return -1 ; if(copytmemtocbuf(device1,cbhnd1,&wdata,10)!=success ){ puts(it failed to copy data to communication buffer.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 63 application note u14371ej1v0an00 (15) copytmemtotmem() [description] copies srcaddr + nsize - 1 address data from the srcaddr address of memory on the target device from the dstaddr address to the dstaddr + nsize - 1 address. sword copytmemtocbuf( devhnd device, /* target device handle */ dword srcaddr, /* source address (srcaddr + 0x10000 in case of ymem) */ dword dstaddr, /* destination address (srcaddr + 0x10000) */ word n /* copy size */ ); [return value] success ... copy was successful. devhnd_error ... a device handle that cannot be recognized has been specified. fail ... communication with the dsp failed, or a parameter is abnormal. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(copytmemtotmem(device1,0x0000,0x0010,0x10)!=success ){ puts(it failed to copy data.) ; } if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 64 application note u14371ej1v0an00 6.2.4 host api management functions (1) loadinformationfile() [description] analyzes the information file specified by infile and saves the analysis data to the previously secured inffile type devinf. sword loadinformationfile( lpcstr infile /* information file pointer */ ); be sure to call this function prior to using the api functions in order to perform data communication with the target device, based on the information obtained from the information file. moreover, if the file name specified in infile is not described as a full path, it is judged to exist in the windows system folder (drive name: /windows/system). [return value] success ... normal termination file_notfound ... specified file could not be found subtaskbl_full ... number of subtasks exceeding the number of max_sub_task of hapiucfg.h fail ... abnormal termination [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success){ puts(it failed to get information.) ; return C1 ; } if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 65 application note u14371ej1v0an00 (2) showinfocontentsall() [description] displays the information loaded with loadinformationfile(). if return_to_window is defined, the information is displayed to a message box on windows, and if return_to_window is not defined, the information is output as standard output. voidshowinfocontentsall( devhnd device /* target device handle */ ); the displayed items consist of the device name, i/o port address of the hdt/hst register and its bit assignment, and the read/write communication buffer information. [return value] there are no return values. [code example] int main() { devhnd device1 ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; showinfocontentsall(device1) ; if(closedev(device1)!=success) return -1 ; return 0; }
chapter 6 api functions 66 application note u14371ej1v0an00 (3) hextobuf() [description] analyzes extension intel hex files and copies srcaddr + nsize - 1 address data from the srcaddr address from the destptr address of memory on the host processor to the destptr + nsize - 1 address. sword hextobuf( word hextype /* hex file type */ lpcstr infile, /* file name pointer */ word srcaddr, /* source address */ lpword destptr, /* destination pointer */ word nsize /* copy size */ ); specify inst as the hex file type in the case of an instruction (for example .hxi file), and data in the case of data (for example, .hdx or .hdy file). [return value] success ... save was successful. fail ... save failed. [code example] int main() { devhnd device1 ; unsigned short dest[10] ; if(loadinformationfile(devinfo.ini)!=success) return -1 ; if(opendev(&device1,device1)!=success ) return -1 ; if(setcommunicatevalue(device1,0x0000)!=success) return -1 ; if(hextobuf(device1.hdx,0x10,dest,10)!=success ){ puts(it failed to opendevice.) ; return -1 ; } if(closedev(device1)!=success) return -1 ; return 0; }
application note u14371ej1v0an00 67 chapter 7 bios functions 7.1. action upon occurrence of hi interrupt bios, through allocation of a specific bios function, realizes that function as the action upon occurrence of a hi interrupt or ho interrupt. in the initial state of the bios (communication disabled mode), echoword: is allocated as the action upon occurrence of an hi interrupt. at this time, by calling opendev(), which is an api function on the user application, the action upon occurrence of an hi interrupt changes to interpreter:. from this status onward, the mode is the communication enabled mode until the action upon occurrence of an hi interrupt is changed back to echoword:. in the case of the interpreter: action, depending on the received hdt value (command), either the action upon occurrence of the next hi interrupt is set to echoword:, selpcmd:, or idtagcmd: is executed. in the case of selpcmd:, following reception of the previously set number of parameters, the specified bios function is executed. in the case of idtagcmd:, the bios function created by the user is executed. 7.2. bios functions (1) echoword: [description] this is an action that corresponds to the hi interrupt when no communication path has been established. when *hdt:x is 0x5555 (request to establish communication path), the action corresponding to the subsequent hi interrupts is changed from echoword: to interpreter:. if *hdt:x is other than 0x5555, a complement of 1 is written to hdt, and the action corresponding to the hi interrupt does not change. [parameters] *hdt:x ... 0x5555 (request to establish communication path) or other data [return value] *hdt:x ... complement of 1 corresponding to input value
chapter 7 bios functions application note u14371ej1v0an00 68 (2) interpreter [description] this is an action that corresponds to the hi interrupt when a communication path is established. a command is input for the higher 8 bits of *hdt:x, and an operand is input for the lower 8 bits. depending on the shift amount used to normalize the command to 32 bits, the operation jumps to the following functions. table 7-1. shift amount and jump destination shift amount jump destination 0selpcmd: 1 idtagcmd: 2 to 7 empty moreover, the user can freely define a function for the empty box in table 7-1. in this case, write jmp xxxx (xxxx is the start address of the function) to mediaos_hif_id_vect_10 of mos_hapi.asm. [parameters] *hdt:x ... command, operand [return value] r0l ... operand (3) selpcmd: [description] the address of the jump destination function indicated in r0l is substituted to *_mha_pcmdptr:mem, and the number of parameters of that function to *_mha_nrstpcmdprm:mem, to change the action upon occurrence of the next hi interrupt from interpreter: to puttocmdbuf:. [parameters] r0l ... operand [return value] *_mha_pcmdptr:mem ... address of jump destination function *_mha_nrstpcmdprm:mem ... number of parameters of jump destination function
chapter 7 bios functions application note u14371ej1v0an00 69 (4) puttocmdbuf: [description] stacks the *hdt value to the area with _mha_cmdbuf_base:mem as its start. when there have been hi interrupts *_mha_nrstpcmdprm:mem times, the operation jumps to the *_mha_pcmdptr:mem address after the action upon occurrence of the next hi interrupt is changed from puttocmdbuf: to interpreter:. table 7-2. *_mha_pcmdptr:mem contents and jump destination *_mha_pcmdptr: mem contents jump destination number of parameters 0 reboot: 4 2direct_rx:1 4direct_ry:1 6 direct_wx: 2 8 direct_wy: 2 10 copy_xtox: 3 12 copy_ytoy: 3 14 copy_xtoy: 3 16 copy_ytox: 3 moreover, users can freely define new functions in the part past 18 in table 7-2. in this case, describe dw xxxx (xxxx is the start address of the function) and dw yyyy (yyyy is the number of parameters) to mediaos_hif_pcmdstruct of mos_hapi.asm. [parameters] *_mha_pcmdptr:mem address of jump destination function *_mha_nrstpcmdprm:mem number of parameters of jump destination function [return value] *_mha_cmdbuf_base+?:mem stack data, depends on number of parameters remark ? = 0 to number of parameters
chapter 7 bios functions application note u14371ej1v0an00 70 (5) idtagcmd: [description] jumps to the user defined function indicated by r0l. the definition method is to describe jmp xxxx (xxxx is the start address of the function) to mediaos_hif_id_vect_20 of mos_hapi.asm. the instruction of the address indicated by id_tag_20xx:+r0l is executed. [parameters] r0l ... jump destination function id [return value] there are no return values. (6) reboot: [description] sets *_mha_cmdbuf_base+2:mem to dp7, *_mha_cmdbuf_base+0:mem to dp3, *_mha_cmdbuf_base+1:mem to dp0, and *hdt:x to r71, and executes dp0. table 7-3. call addresses and reboot routines call address reboot routine 1 y memory ? instruction memory word reboot 2 x memory ? instruction memory word reboot 3 y memory ? instruction memory byte reboot 4 x memory ? instruction memory byte reboot 5 hdt ? instruction memory reboot [parameters] *mha_cmdbuf_base+2:mem ... dp7 value *mha_cmdbuf_base+1:mem ... call address *mha_cmdbuf_base+0:mem ... dp3 value [return value] there are no return values. (7) direct_rx: [description] read the data of the *hdt:x address of x memory and writes it to *hdt:x. [parameters] *hdt:x ... read address [return value] *hdt:x ... read data
chapter 7 bios functions application note u14371ej1v0an00 71 (8) direct_ry: [description] reads the data of the *hdt:x address of y memory and writes it to *hdt:x. [parameters] *hdt:x ... read address [return value] *hdt:x ... read data (9) direct_wx: [description] writes the *hdt:x value to the *_mha_cmdbuf_base+0:mem of x memory. [parameters] *_mha_cmdbuf_base+0:mem ... write address *hdt:x ... write data [return value] there are no return values. (10) direct_wy: [description] writes the *hdt:x value to the *_mha_cmdbuf_base+0:mem address of y memory. [parameters] *_mha_cmdbuf_base+0:mem ... write address *hdt:x ... write data [return value] there are no return values. (11) copy_xtox: [description] copies the data of the *hdt:x size area from the *_mha_cmdbuf_base+0:mem address of x memory from the *_mha_cmdbuf_base+1:mem address of the same memory to the *hdt:x size area. [parameters] *mha_cmdbuf_base+1:mem ... source start address *mha_cmdbuf_base+0:mem ... destination start address *hdt:x ... copy size [return value] there are no return values.
chapter 7 bios functions application note u14371ej1v0an00 72 (12) copy_ytoy: [description] copies the data of the *hdt:x size area from the *_mha_cmdbuf_base+0:mem address of y memory from the *_mha_cmdbuf_base+1:mem address of the same memory to the *hdt:x size area. [parameters] *_mha_cmdbuf_base+1:mem+0 ... source start address *_mha_cmdbuf_base+0:mem+1 ... destination start address *hdt:x ... copy size [return value] there are no return values. (13) copy_xtoy: [description] copies the data of the *hdt:x size area from the *_mha_cmdbuf_base+0:mem address of x memory from the *_mha_cmdbuf_base+1:mem address of y memory to the *hdt:x size area. [parameters] *_mha_cmdbuf_base+1:mem+0 ... source start address *_mha_cmdbuf_base+0:mem+1 ... destination start address *hdt:x ... copy size [return value] there are no return values. (14) copy_ytox: [description] copies the data of the *hdt:x size area from the *_mha_cmdbuf_base+0:mem address of y memory from the *_mha_cmdbuf_base+1:mem address of x memory to the *hdt:x size area. [parameters] *_mha_cmdbuf_base+1:mem+0 ... source start address *_mha_cmdbuf_base+0:mem+1 ... destination start address *hdt:x ... copy size [return value] there are no return values.
chapter 7 bios functions application note u14371ej1v0an00 73 (15) readfromcbuf: [description] reads 1 data from the used area indicated by r0l of the write communication buffer, and substitutes it to r1l. this function is called directly from a subtask on the dsp. moreover, when this function is called by several tasks, it is necessary to prohibit interrupts used as a timer (interrupt defined with _used_timerint of os_udef.h) beforehand. the value specified by r0l is determined in the order that the used areas are prepared. if, a new used area is to be prepared following the deletion of a used area, that deleted value is allocated. for example, if three used areas have been created with the createcbuf() api function, the creation order, 0, 1, 2, is used. createcbuf(device,3,write,&cbhnda); ... r0l = 0 if this used area is to be read createcbuf(device,5,write,&cbhndb); ... r0l = 1 if this used area is to be read createcbuf(device,4,write,&cbhndc); ... r0l = 2 if this used area is to be read then, even if the used area that was created second (cbhndb) is deleted, the values specified to r0l of the used areas created first and second remain 0 and 2. freecbuf(cbhndb); ... if the buffers created first and third are to be read, r0l remains 0 and 2. then, if a new fourth used area is created, the value specified for r0l is 1. createcbuf(device,6,write,&cbhndd); ... if this buffer is to be read, r0l = 1 moreover, if a new fifth used area is created, the value specified for r0l is 3. createcbuf(device,7,write,&cbhnde); ... if this buffer is to be read, r0l is 3. in the same way, if a used area is deleted thereafter, the values specified until now for r0l do not change, and if a new used area is created thereafter, the vacant value is filled. if there is no vacant value, a new value is allocated. since the r0l value allocation matches the contents of cbhnd at the time the used area is created, it is possible to use that value to subtasks. createcbuf(device,3,write,&cbhnda); ... if this buffer is to be read, r0l = cbhnda, so that a program that in one way or another directs the subtasks must be created. in the case of this function, the data corresponding to the used area must all be read. after this function has read the data corresponding to the used area, data write to that used area is enabled. in the following example, the contents of a size 5 used area are read and stored to the address displayed with dp0. r0l=0 ; loop 0x5{ call readfromcbuf ; *dp0++=r1l ; }
chapter 7 bios functions application note u14371ej1v0an00 74 in the case of this function, if the data of the used area to be read has already been read, or if it has not been written, 1 is set to r2l as the return value and data read is not performed for the used area. in this case, it is not necessary to call this function the number of times corresponding to the used area size. in the following example, a loop is exited in case read is not possible. clr(r2l) ; r0l=0 ; loop 0x5{ call readfromcbuf ; if(r2==0) jmp $+2 lpop ; *dp0++=r1l ; nop ; } [parameters] r0l ... write communication buffer handle [return value] r1l ... read data r2l ... 0: normal termination, 1: abnormal termination (data has already been read or data cannot be read because there is no data.) (16) writetocbuf: [description] writes the contents of r1l to the used area indicated by r0l of the read communication buffer. this function is called directly from a subtask on the dsp. moreover, when this function is called by several tasks, it is necessary to prohibit interrupts used as a timer (interrupt defined with _used_timerint of os_udef.h) beforehand. the value specified by r0l is determined in the order that the used areas are prepared. if, a new used area is to be prepared following the deletion of a used area, that deleted value is allocated. for example, if three read communication buffer used areas have been created with the createcbuf() api function, the creation order, 0, 1, 2, is used. createcbuf(device,3,read,&chnda); ... r0l = 0 if this buffer is to be written createcbuf(device,5,read,&chndb); ... r0l = 1 if this buffer is to be written createcbuf(device,4,read,&chndc); ... r0l = 2 if this buffer is to be written then, even if the used area that was created second (cbhndb) is deleted, the values specified to r0l of the used areas created first and third remain 0 and 2. freecbuf(dbhndb); ... if the buffers created first and third are to be written, r0l remains 0 and 2. then, if a new fourth used area is created, the value specified for r0l is 1. createcbuf(device,6,read,&cbhndd); ... if this buffer is to be written, r0l = 1 moreover, if a new fifth used area is created, the value specified for r0l is 3. createcbuf(device,7,read,&cbhnde); ... if this buffer is to be written, r0l = 3
chapter 7 bios functions application note u14371ej1v0an00 75 in the same way, if a used area is newly created thereafter without changing the value specified until now to r0l, the vacant value is filled. if there is no vacant value, a new value is allocated. since the above value allocations match the and masked contents with 0x7fff to cbhnd at the time the used area is created, it is possible to use that value to subtasks. createcbuf(device,3,read,&cbhnda); ... if this buffer is to be written, r0l = cbhnda&0x7fff, so that a program that in one way or another directs the subtasks must be created. in the case of this function, the data corresponding to the used area must all be read. after this function has read the data corresponding to the used area, data write to that used area is enabled. in the following example, the contents of a size 5 used area are read and stored to the address displayed with dp0. r0l=0 ; loop 0x5{ r1l=*dp0++ ; call writetocbuf ; } in the case of this function, if the data of the used area to be read has not yet been read, 1 is set to r2l as the return value and data read is not performed. in this case, it is not necessary to call this function the number of times corresponding to the used area size. in the following example, a loop is exited in case read is not possible. clr(r2l) ; r0l=0 ; loop 0x5{ r1l=*dp0++ ; call writetocbuf ; if(r2==0) jmp $+2 lpop ; nop ; nop ; } [parameters] r0l ... read communication buffer handle r1l ... write data [return value] r2l ... 0: normal termination, 1: abnormal termination (write cannot be performed because data that has been written previously remains.)
application note u14371ej1v0an00 76 [memo]
application note u14371ej1v0an00 77 chapter 8 preparation of host api execution file 8.1 preparation of execution file using api functions to prepare an execution file using api functions, compile user applications that call api functions with a c compiler, and link them with mos_hapi.c, spx.c object files (which must be compiled beforehand). moreover, user settings or a program adjusted to the target system must be prepared in the next file. 8.1.1 hapiucfg.h hapiucfg.h is a user definition header file of mos_hapi.c, spx.c. the following settings adjusted to the target system are required. (1) wait_time, tim_const definition #define wait_timexx ... write a value for xx. #define tim_constyy ... write a value for yy. wait_time and tim_const definitions define the time to be waited until the host read enable flag or host write enable flag of the hst register changes to 1 (read, write enable), using functions that access the hdt register of the dsp within spx.c (inhdtw(), outhdtw()). the wait time is determined by wait_time * tim_const. if the character constants wait_time and tim_const in inhdtw(), outhdtw() are not used, these definition statements can be deleted. (2) hdtaccess, hstaccess, rstaccess definitions #define hdtaccess x ... describe 0:byte access or 1:word access for x. #define hstaccess y ... describe 0:byte access or 1:word access for y. #define rstaccess z ... describe 0:byte access or 1:word access for z. the hdtaccess, hstaccess, and rstaccess definitions define whether the hdt register, hst register, and rst pin are to be accessed using byte access or word access. if the hdtaccess, hstaccess, rstaccess character constants are not used for the functions accessing the hdt register, hst register, and rst pin (inhdtw(), outhdtw(), systemreset()), these definition statements can be deleted. (3) max_sub_task definition #define max_sub_task xx ... write a value for xx. the max_sub_task definition defines the maximum number of used subtasks. the defined value can be larger than the number of subtasks that is actually used, but if it is smaller, the subtaskbl_full error occurs upon execution of loadinformationfile(). (4) num_hicbuf, num_hocbuf definitions #define num_hicbuf xx ... write a value for xx. #define num_hocbuf yy ... write a value for yy. num_hicbuf and num_hocbuf definitions define the number of used areas for the write communication buffer and read communication buffer, respectively, that can be prepared. the defined value can be larger than the number of communication buffers that are actually prepared, but if it is smaller, the cbtbl_ful error occurs upon execution of createcbuf().
chapter 8 preparation of host api execution file application note u14371ej1v0an00 78 8.1.2 spx.c spx.c is the source file for the interface between api functions and the dsp. regarding the functions listed below, a program adjusted to the target system must be prepared. word inhdtw(config cmconfig) ... function to write data to hdt word outhdtw(config cmconfig, word dataword) ... function to read data from hdt void systemreset(config cmconfig) ... function to perform system reset
chapter 8 preparation of host api execution file application note u14371ej1v0an00 79 8.2 preparation of execution file using bios functions to prepare an execution file that uses bios functions, insert the necessary code to the initialization block of the target system of the RX77016 (_mos_targetsysinit:) and hi interrupt handler code block (_mos_ivhi:), and following assembly in the wb77016, perform linking of the RX77016 with the bios_fns.asm object file (which must be assembled beforehand), in order to create the execution file. the blocks necessary for inserting code or changing definition are as follows. 8.2.1 os_udef.h (1) _used_ivhi definition #define _used_ivhi true ; hi (itn9) true:used false:not used the _used_ivhi definition must be true. (2) _ival_eir, _ival_srormask, _ival_srandmask definitions #define _ival_eir xx ; eir #define _ival_srormask xx ; or mask value for sr. #define _ival_srandmask xx ; and mask value for sr. the _ival_eir, _ival_srormask, and _ival_srandmask definitions must be definitions that enable hi interrupts. 8.2.2 target system initialization block (_mos_targetsysinit:) in the target system initialization block, the hdt access wait enable bit of the hst register is set and %inithistate(echoword) is executed. moreover, biosucfg.h, bios_fns.h, and bios_mac.h must be included prior to %inithistate(echoword). next, a description example for the execution of %inithistate(echoword) is shown. r0l = *hst:x ; r0 = r0 | 0x0400 ; *hst:x = r0l ; %inithistate(echoword) ; 8.2.3 hi interrupt handler code block (_mos_ivhi:) in the hi interrupt handler code block (_mos_ivhi:), the following 4 states are described. moreover, biosucfg.h and bios_fns.h must be included prior to r0i=*_mha_mdrg_in:mem. clr(r0) ; r0l = *_mha_mdrg_in:mem ; dp0 = r0l; jmp dp0;;
chapter 8 preparation of host api execution file application note u14371ej1v0an00 80 8.2.4 biosucfg.h biosucfg.h is a header file for the initialization block (_mos_targetsysinit:) of the target system of the RX77016, hi interrupt handler code block (_mos_ivhi:), and bios_fns.asm, and the following settings adjusted to the target system are required. (1) _mha_datamem definition #define_mha_datamemx ... write 0:xmem or 1:ymem for x. in the _mha_datamem definition, allocations to xmem or ymem of the data area required for execution of the communication buffer information and heap area, and other bios functions can be done. (2) have_exram definition #define have_exramx ... write 0:internal ram or 1:external ram for x. in the have_exram definition, allocation of all instructions and data required for execution of bios functions can be done to internal ram or external ram. (3) cmd_buf_size definition #define cmd_buf_sizex ... write a value for x. in the cmd_buf_size definition, the stack area size of the parameters used in puttocmdbuf: is defined. describe the maximum number of parameter stacks required for the execution of bios functions. (4) hicbuf_heap_size, num_hicbuf definitions #define hicbuf_heap_sizex ... write a value for x. #define num_hicbufy ... write a value for y. the hicbuf_heap_size and num_hicbuf definitions define the write communication buffer heap area size and the number of buffers that can be prepared. (5) hocbuf_heap_size, num_hocbuf definitions #define hocbuf_heap_sizex ... write a value for x. #define num_hocbufy ... write a value for y. the hocbuf_heap_size and num_hocbuf definitions define the read communication buffer heap area size and the number of buffers that can be prepared.
although nec has taken all possible steps to ensure that the documentation supplied to our customers is complete, bug free and up-to-date, we readily accept that errors may occur. despite all the care and precautions we've taken, you may encounter problems in the documentation. please complete this form whenever you'd like to report errors or suggest improvements to us. hong kong, philippines, oceania nec electronics hong kong ltd. fax: +852-2886-9022/9044 korea nec electronics hong kong ltd. seoul branch fax: 02-528-4411 taiwan nec electronics taiwan ltd. fax: 02-2719-5951 address north america nec electronics inc. corporate communications dept. fax: 1-800-729-9288 1-408-588-6130 europe nec electronics (europe) gmbh technical documentation dept. fax: +49-211-6503-274 south america nec do brasil s.a. fax: +55-11-6462-6829 asian nations except philippines nec electronics singapore pte. ltd. fax: +65-250-3583 japan nec semiconductor technical hotline fax: 044-435-9608 i would like to report the following error/make the following suggestion: document title: document number: page number: thank you for your kind support. if possible, please fax the referenced page or drawing. excellent good acceptable poor document rating clarity technical accuracy organization cs 00.6 name company from: tel. fax facsimile message

▲Up To Search▲

Price & Availability of RX77016

	To Download RX77016 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .